home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1997 February / EnigmA AMIGA RUN 15 (1997)(G.R. Edizioni)(IT)[!][issue 1997-02][PLANET CD V].iso / enigma / earcd / musicali / splib52d.lha / superplay-lib_DEV / Programmers / autodocs / SuperPlay_Ref_ENG.doc < prev    next >
Text File  |  1996-11-15  |  17KB  |  712 lines
  1. TABLE OF CONTENTS
  2.  
  3. superplay.library/--background--
  4. superplay.library/SPL_AllocHandle
  5. superplay.library/SPL_FreeHandle
  6. superplay.library/SPL_StopReplay
  7. superplay.library/SPL_FreeResources
  8. superplay.library/SPL_SuperPlay
  9. superplay.library/SPL_SuperWrite
  10. superplay.library/SPL_InitHandleAsDOS
  11. superplay.library/SPL_InitHandleAsClip
  12. superplay.library/SPL_SetWriteType
  13. superplay.library/SPL_GetErrorString
  14. superplay.library/SPL_SetWriteName
  15. superplay.library/SPL_FileInfoRequest
  16. superplay.library/SPL_SetReqIOWindow
  17. superplay.library/SPL_ReadPlayData
  18. superplay.library/SPL_ContinueReplay
  19. superplay.library/SPL_FastForward
  20. superplay.library/SPL_FastBackward
  21. superplay.library/SPL_GetSampleList
  22. superplay.library/SPL_SetSampleList
  23. superplay.library/SPL_GetFileType
  24.  
  25. superplay.library/--background--              superplay.library/--background--
  26.  
  27.    VERSION
  28.         $VER: SuperPlay_Ref_ENG.doc V5.1 (8.8.96)
  29.  
  30.    COPYRIGHT
  31.         © 1995-96 by Andreas R. Kleinert. All rights reserved.
  32.       
  33.         - Feel free to translate this Doc-File into other languages. -
  34.  
  35.    GENERAL
  36.               Andreas R. Kleinert,
  37.               Sandstrasse 1,
  38.               D-57072 Siegen,
  39.               Germany.
  40.     
  41.         EMail:  Fido             Andreas Kleinert 2:2457/350.18
  42.                 Usenet/InterNet  Andreas_Kleinert@superview.ftn.sub.org
  43.     
  44.           If nothing else works, try one of these Fido-InterNet gateways:
  45.     
  46.                 Andreas_Kleinert@p10.f435.n2457.z2.fido.sub.org (in Germany)
  47.                 Andreas_Kleinert@p10.f435.n2457.z2.fidonet.org  (USA or other)
  48.  
  49.    HISTORY
  50.                             V2     bug-fixed ClipBoard-Support
  51.                                    with the supplied SPObjects (ak)
  52.                             V3     created working combination of
  53.                                    SPL_SetSampleList() and SuperWrite()
  54.                                    calls (ak)
  55.                             V4     filetype recognition without loading (ak)
  56.                             V4.6   Autodoc format
  57.                                    SetWriteName: Correct type of write_name
  58.                                    Change two SVL_ prefix to SPL_
  59.                                    Add version behind NAME            (indy)
  60.                             V5.1   SetWriteName parameter must be UBYTE * (ak)
  61.  
  62.  
  63. superplay.library/SPL_AllocHandle           superplay.library/SPL_AllocHandle
  64.  
  65.    NAME
  66.         SPL_AllocHandle  (V1)
  67.  
  68.    SYNOPSIS
  69.  
  70.         APTR SPL_AllocHandle(APTR future)
  71.         D0   -$1e            A1
  72.  
  73.    FUNCTION
  74.  
  75.         Allocates a handle for accessing a Sample/Module via SPObjects.
  76.  
  77.    INPUT(S)
  78.  
  79.         future - always NULL yet
  80.  
  81.    RESULT
  82.  
  83.         A pointer to a new allocated Handle or NULL, if allocation failed.
  84.  
  85.    WARNING
  86.  
  87.         Test, if the result was NULL, or not !
  88.  
  89.    SEE ALSO
  90.  
  91.         SPL_FreeResources, SPL_FreeHandle
  92.  
  93. superplay.library/SPL_FreeHandle             superplay.library/SPL_FreeHandle
  94.  
  95.    NAME
  96.         SPL_FreeHandle  (V1)
  97.  
  98.    SYNOPSIS
  99.  
  100.         VOID SPL_FreeHandle(APTR handle)
  101.         D0   -$24           A1
  102.  
  103.    FUNCTION
  104.  
  105.        Stops playing, frees all Resources and delocates a Handle, which has
  106.        been allocated with SPL_AllocHandle before.
  107.  
  108.    INPUT(S)
  109.  
  110.         handle - a valid handle
  111.  
  112.    RESULT
  113.  
  114.         -
  115.  
  116.    SEE ALSO
  117.  
  118.         SPL_AllocHandle, SPL_StopReplay, SPL_FreeResources
  119.  
  120. superplay.library/SPL_StopReplay             superplay.library/SPL_StopReplay
  121.  
  122.    NAME
  123.         SPL_StopReplay  (V1)
  124.  
  125.    SYNOPSIS
  126.  
  127.         VOID SPL_StopReplay(APTR handle)
  128.         D0   -$2a           A1
  129.  
  130.    FUNCTION
  131.  
  132.         Stops playing the Sample/Module, indentified by the handle.
  133.         Some SPObjects support to continue the Sample/Module with
  134.         SPL_ContinueReplay after calling SPL_StopReplay.
  135.  
  136.    INPUT(S)
  137.  
  138.         handle - a valid handle
  139.  
  140.    RESULT
  141.  
  142.         -
  143.  
  144.    SEE ALSO
  145.  
  146.         SPL_ContinueReplay, SPL_FreeResources, SPL_FreeHandle
  147.  
  148. superplay.library/SPL_FreeResources       superplay.library/SPL_FreeResources
  149.  
  150.    NAME
  151.         SPL_FreeResources (V1)
  152.  
  153.    SYNOPSIS
  154.  
  155.         VOID SPL_FreeResources(APTR handle)
  156.         D0   -$30              A1
  157.  
  158.    FUNCTION
  159.  
  160.         Frees all resources belonging to the specific Sample/Module,
  161.         indentified by the handle, which are not needed to just replay it.
  162.         Playing of the Sample/Module is not stopped and/or interrupted.
  163.  
  164.    INPUT(S)
  165.  
  166.         handle - a valid handle
  167.  
  168.    RESULT
  169.  
  170.         -
  171.  
  172.    SEE ALSO
  173.  
  174.         SPL_AllocHandle, SPL_StopReplay, SPL_FreeHandle
  175.  
  176. superplay.library/SPL_SuperPlay               superplay.library/SPL_SuperPlay
  177.  
  178.    NAME
  179.         SPL_SuperPlay  (V1)
  180.  
  181.    SYNOPSIS
  182.  
  183.         ULONG SPL_SuperPlay(APTR handle, char *filename)
  184.         D0    -$36          A1           A2
  185.  
  186.    FUNCTION
  187.  
  188.         Loads and plays the Sample/Module described by FileName.
  189.         The handle is initialized and the fitting SPObject is opened
  190.         and accessed for replaying the Sample/Module.
  191.  
  192.         Playing can be stopped either via full delocation of the handle
  193.         or temporal interruption with SPL_StopReplay.
  194.  
  195.    INPUT(S)
  196.  
  197.         handle   - a valid handle
  198.         filename - a valid AmigaDOS FilePath and -Name
  199.  
  200.    RESULT
  201.  
  202.         NULL or an adequate SPERR-Errorcode.
  203.  
  204.    SEE ALSO
  205.  
  206.         SPL_AllocHandle, SPL_StopReplay, SPL_ContinueReplay,
  207.         SPL_FastForward, SPL_FastBackward, SPL_FreeHandle
  208.  
  209. superplay.library/SPL_SuperWrite             superplay.library/SPL_SuperWrite
  210.  
  211.    NAME
  212.         SPL_SuperWrite  (V1)
  213.  
  214.    SYNOPSIS
  215.  
  216.         ULONG SPL_SuperWrite(APTR handle, APTR source_handle)
  217.         D0    -$3c           A1           A2
  218.  
  219.    FUNCTION
  220.  
  221.         Usually a Sample/Module is loaded AND played via SPL_SuperPlay :
  222.         No separate reading and playing calls are done.
  223.  
  224.         For writing - that means : converting - a Sample/Module, you
  225.         have to use the following order :
  226.  
  227.         source_handle = SPL_AllocHandle(N);
  228.         result        = SPL_ReadPlayData(source_handle, source_name);
  229.         dest_handle   = SPL_AllocHandle(N);
  230.         /* result     = SPL_InitHandleAsDOS(dest_handle, N); */ /* default */
  231.         result        = SPL_SetWriteName(dest_handle, dest_name, N);
  232.         result        = SPL_SetWriteType(dest_handle, dest_type, N);
  233.         result        = SPL_SuperWrite(dest_handle, source_handle);
  234.         SPL_FreeHandle(dest_handle);
  235.         SPL_FreeHandle(source_handle);
  236.  
  237.  
  238.         Also : Check the "result" value AFTER EACH function call (see
  239.                Example SourceCodes) !
  240.  
  241.         All available values for dest_type can be found in the specific
  242.         SPOBject-List in the SuperPlayBase.
  243.         The values WILL change with every re-initialization of
  244.         superplay.library, so update them with every new opening !
  245.  
  246.         If "source_handle" is NULL,
  247.         it is checked, whether a SampleList has been set via
  248.         "SPL_SetSampleList()", and then this SampleList is completely
  249.         saved.
  250.  
  251.         It is suggested to use the old style for converting between
  252.         FileFormats and the new style for saving single (self-created)
  253.         SampleLists.
  254.  
  255.    INPUT(S)
  256.  
  257.         handle        - a valid handle        (used for Write Access)
  258.         source_handle - an other valid handle (used for Read Access)
  259.  
  260.    RESULT
  261.  
  262.         NULL or an adequate SPERR-Errorcode.
  263.  
  264.    SEE ALSO
  265.  
  266.  
  267.  
  268.         SPL_AllocHandle, SPL_ReadPlayData, SPL_FreeHandle
  269.  
  270. superplay.library/SPL_InitHandleAsDOS   superplay.library/SPL_InitHandleAsDOS
  271.  
  272.    NAME
  273.         SPL_InitHandleAsDOS (V1)
  274.  
  275.    SYNOPSIS
  276.  
  277.         ULONG SPL_InitHandleAsDOS(APTR handle, APTR future)
  278.         D0    -$42                A1           A2
  279.  
  280.    FUNCTION
  281.  
  282.         Initializes a Handle for AmigaDOS access, so that the given
  283.         AmigaDOS FileNames are used.
  284.         Another possibility is sometimes to initialize Handles
  285.         for ClipBoard Access (depending on the specific SPObject,
  286.         e.g. IFF-8SVX).
  287.  
  288.    INPUT(S)
  289.  
  290.         handle - a valid handle
  291.         future - always NULL yet
  292.  
  293.  
  294.    RESULT
  295.  
  296.         NULL or an adequate SPERR-Errorcode.
  297.  
  298.    SEE ALSO
  299.  
  300.  
  301.  
  302.         SPL_InitHandleAsClip
  303.  
  304. superplay.library/SPL_InitHandleAsClip superplay.library/SPL_InitHandleAsClip
  305.  
  306.    NAME
  307.         SPL_InitHandleAsClip  (V1)
  308.  
  309.    SYNOPSIS
  310.  
  311.         ULONG SPL_InitHandleAsClip(APTR handle, APTR future)
  312.         D0    -$48                 A1           A2
  313.  
  314.    FUNCTION
  315.  
  316.         Initializes a Handle for ClipBoard access, so that the (possibly)
  317.         given AmigaDOS FileNames are ignored.
  318.         The nearly always used possibility is to initialize Handles
  319.         for AmigaDOS Access (supported by ALL SPObjects).
  320.  
  321.    INPUT(S)
  322.  
  323.         handle - a valid handle
  324.         future - always NULL yet
  325.  
  326.  
  327.    RESULT
  328.  
  329.         NULL or an adequate SPERR-Errorcode.
  330.  
  331.    SEE ALSO
  332.  
  333.         SPL_InitHandleAsDOS
  334.  
  335. superplay.library/SPL_SetWriteType         superplay.library/SPL_SetWriteType
  336.  
  337.    NAME
  338.         SPL_SetWriteType  (V1)
  339.  
  340.    SYNOPSIS
  341.  
  342.         ULONG SPL_SetWriteType(APTR handle, ULONG write_type, APTR future)
  343.         D0    -$4e             A1           A2                A3
  344.  
  345.    FUNCTION
  346.  
  347.         Sets the write_type for a SPL_SuperWrite() call.
  348.         See description there and example SourceCodes for more and
  349.         detailed information.
  350.  
  351.    INPUT(S)
  352.  
  353.         handle     - a valid handle
  354.         write_type - a valid temporary write_type code form the SPObject List
  355.         future     - always NULL yet
  356.  
  357.  
  358.    RESULT
  359.  
  360.         NULL or an adequate SPERR-Errorcode.
  361.  
  362.    SEE ALSO
  363.  
  364.         SPL_SuperWrite
  365.  
  366. superplay.library/SPL_GetErrorString     superplay.library/SPL_GetErrorString
  367.  
  368.    NAME
  369.         SPL_GetErrorString  (V1)
  370.  
  371.    SYNOPSIS
  372.  
  373.         char * SPL_GetErrorString(ULONG error_code)
  374.         D0    -$54                A1
  375.  
  376.    FUNCTION
  377.  
  378.         Returns the Error Message for a specific Error Code, returned
  379.         by any function of the superplay.library.
  380.  
  381.    INPUT(S)
  382.  
  383.         error_code - any SPERR Error Code
  384.  
  385.    RESULT
  386.  
  387.         read-only pointer to a SPERR Error String
  388.  
  389.    SEE ALSO
  390.  
  391.         -
  392.  
  393. superplay.library/SPL_SetWriteName         superplay.library/SPL_SetWriteName
  394.  
  395.    NAME
  396.         SPL_SetWriteName  (V1)
  397.  
  398.    SYNOPSIS
  399.  
  400.         ULONG SPL_SetWriteNameClip(APTR handle, UBYTE *write_name, APTR future)
  401.         D0    -$5a                 A1           A2                 A3
  402.  
  403.    FUNCTION
  404.  
  405.         Sets the write_name for a SPL_SuperWrite() call.
  406.         See description there and example SourceCodes for more and
  407.         detailed information.
  408.  
  409.    INPUT(S)
  410.  
  411.         handle     - a valid handle
  412.         write_name - a valid AmigaDOS FilePath and -Name description
  413.         future     - always NULL yet
  414.  
  415.  
  416.    RESULT
  417.  
  418.         NULL or an adequate SPERR-Errorcode.
  419.  
  420.    SEE ALSO
  421.  
  422.         SPL_SuperWrite
  423.  
  424. superplay.library/SPL_FileInfoRequest   superplay.library/SPL_FileInfoRequest
  425.  
  426.    NAME
  427.         SPL_FileInfoRequest  (V1)
  428.  
  429.    SYNOPSIS
  430.  
  431.         ULONG SPL_FileInfoRequest(APTR handle, struct Window *window,
  432.         D0    -$60                A1           A2
  433.  
  434.                                   APTR future)
  435.                                   A3
  436.  
  437.    FUNCTION
  438.  
  439.         Pops up an Info-Requester with more or less detailed information
  440.         on the currently loaded Sample/Module.
  441.         A window pointer may be given to select the place to pop it up.
  442.  
  443.    INPUT(S)
  444.  
  445.         handle - a valid handle
  446.         window - a valid Window Pointer or NULL
  447.         future - always NULL yet
  448.  
  449.  
  450.    RESULT
  451.  
  452.         NULL or an adequate SPERR-Errorcode.
  453.  
  454.    SEE ALSO
  455.  
  456.         SPL_SetReqIOWindow
  457.  
  458. superplay.library/SPL_SetReqIOWindow     superplay.library/SPL_SetReqIOWindow
  459.  
  460.    NAME
  461.         SPL_SetReqIOWindow  (V1)
  462.  
  463.    SYNOPSIS
  464.  
  465.         ULONG SPL_SetReqIOWindow(APTR handle, struct Window *window)
  466.         D0    -$66               A1           A2
  467.  
  468.    FUNCTION
  469.  
  470.         Sets a new Default-Window (default : IntuitionBase->FirstWindow)
  471.         for any Requester IO.
  472.  
  473.    INPUT(S)
  474.  
  475.         handle - a valid handle
  476.         window - a valid Window Pointer or NULL
  477.  
  478.    RESULT
  479.  
  480.         NULL or an adequate SPERR-Errorcode.
  481.  
  482.    SEE ALSO
  483.  
  484.         SPL_FileInfoReq
  485.  
  486. superplay.library/SPL_ReadPlayData         superplay.library/SPL_ReadPlayData
  487.  
  488.    NAME
  489.         SPL_ReadPlayData  (V1)
  490.  
  491.    SYNOPSIS
  492.  
  493.         ULONG SPL_ReadPlayData(APTR handle, char *filename)
  494.         D0    -$6c             A1           A2
  495.  
  496.    FUNCTION
  497.  
  498.         Loads but NOT plays the data of the Sample/Module described by
  499.         FileName.
  500.         The handle is initialized and the fitting SPObject is opened
  501.         to access the Sample/Module data for use with SPL_SuperWrite.
  502.  
  503.    INPUT(S)
  504.  
  505.         handle   - a valid handle
  506.         filename - a valid AmigaDOS FilePath and -Name
  507.  
  508.    RESULT
  509.  
  510.         NULL or an adequate SPERR-Errorcode.
  511.  
  512.    SEE ALSO
  513.  
  514.         SPL_SetWriteName, SPL_SetWriteType, SPL_SuperWrite
  515.  
  516. superplay.library/SPL_ContinueReplay     superplay.library/SPL_ContinueReplay
  517.  
  518.    NAME
  519.         SPL_ContinueReplay  (V1)
  520.  
  521.    SYNOPSIS
  522.  
  523.         ULONG SPL_ContinueReplay(APTR handle)
  524.         D0    -$72               A1
  525.  
  526.    FUNCTION
  527.  
  528.         Some SPObjects support to continue a Sample/Module which
  529.         has been stopped by calling SPL_StopReplay.
  530.  
  531.    INPUT(S)
  532.  
  533.         handle - a valid handle
  534.  
  535.    RESULT
  536.  
  537.         NULL or an adequate SPERR-Errorcode.
  538.  
  539.    SEE ALSO
  540.  
  541.         SPL_SuperPlay, SPL_StopReplay
  542.  
  543. superplay.library/SPL_FastForward           superplay.library/SPL_FastForward
  544.  
  545.    NAME
  546.         SPL_FastForward  (V1)
  547.  
  548.    SYNOPSIS
  549.  
  550.         ULONG SPL_FastForward(APTR handle)
  551.         D0    -$78            A1
  552.  
  553.    FUNCTION
  554.  
  555.         Some SPObjects might support a "cassette recorder"-like way
  556.         to browse trough a Sample/Module via FastForward and Rewind.
  557.  
  558.    INPUT(S)
  559.  
  560.         handle - a valid handle
  561.  
  562.    RESULT
  563.  
  564.         NULL or an adequate SPERR-Errorcode.
  565.  
  566.    SEE ALSO
  567.  
  568.         SPL_FastBackward
  569.  
  570. superplay.library/SPL_FastBackward         superplay.library/SPL_FastBackward
  571.  
  572.    NAME
  573.         SPL_FastBackward  (V1)
  574.  
  575.    SYNOPSIS
  576.  
  577.         ULONG SPL_FastBackward(APTR handle)
  578.         D0    -$7e            A1
  579.  
  580.    FUNCTION
  581.  
  582.         Some SPObjects might support a "cassette recorder"-like way
  583.         to browse trough a Sample/Module via FastForward and Rewind.
  584.  
  585.    INPUT(S)
  586.  
  587.         handle - a valid handle
  588.  
  589.    RESULT
  590.  
  591.         NULL or an adequate SPERR-Errorcode.
  592.  
  593.    SEE ALSO
  594.  
  595.         SPL_FastForward
  596.  
  597. superplay.library/SPL_GetSampleList       superplay.library/SPL_GetSampleList
  598.  
  599.    NAME
  600.         SPL_GetSampleList  (V2)
  601.  
  602.    SYNOPSIS
  603.  
  604.         ULONG SPL_GetSampleList(APTR handle, struct SPO_SampleList **list)
  605.         D0    -$84              A1           A2
  606.  
  607.    FUNCTION
  608.  
  609.         While/after loading a Sample-File Version 2 SPObjects might create
  610.         a special list of all Samples, which appear in the File.
  611.         This will usually be one one Sample for SampleFiles, but many more
  612.         for ModuleFiles.
  613.  
  614.         Not all SPObjects, especially not all ModuleType-SPObjects,
  615.         may support this and will return an error value or an empty list.
  616.  
  617.    INPUT(S)
  618.  
  619.         handle - a valid handle
  620.         list   - a pointer to a SPO_SampleList pointer
  621.  
  622.    RESULT
  623.  
  624.         NULL or an adequate SPERR-Errorcode.
  625.  
  626.    SEE ALSO
  627.  
  628.         SPL_SetSampleList
  629.  
  630. superplay.library/SPL_SetSampleList       superplay.library/SPL_SetSampleList
  631.  
  632.    NAME
  633.         SPL_SetSampleList  (V2)
  634.  
  635.    SYNOPSIS
  636.  
  637.         ULONG SPL_SetSampleList(APTR handle, struct SPO_SampleList *list)
  638.         D0    -$8a              A1           A2
  639.  
  640.    FUNCTION
  641.  
  642.         For saving Sample-Files with Version 2 SPObjects, there may be used
  643.         a special list of all Samples, which should appear in the File.
  644.  
  645.         This will usually be one one Sample for SampleFiles, but many more
  646.         for ModuleFiles.
  647.  
  648.         Not all SPObjects, especially not all ModuleType-SPObjects,
  649.         may support this and can return SPERR_ACTION_NOT_SUPPORTED.
  650.  
  651.    INPUT(S)
  652.  
  653.         handle - a valid handle
  654.         list   - a pointer to a SPO_SampleList
  655.  
  656.    RESULT
  657.  
  658.         NULL or an adequate SPERR-Errorcode.
  659.  
  660.    SEE ALSO
  661.  
  662.         SPL_GetSampleList
  663.  
  664. superplay.library/SPL_GetFileType          superplay.library/SPL_GetFileType
  665.  
  666.    NAME
  667.         SPL_GetFileType  (V4)
  668.  
  669.    SYNOPSIS
  670.  
  671.         ULONG SPL_GetFileType(APTR handle, char *filename, ULONG *filetype)
  672.         D0    -$90            A1           A2              A3
  673.  
  674.    FUNCTION
  675.  
  676.         Finds out superplay-specific FileType-Code
  677.         (redefined with every re-initialization of the Library) or
  678.         SP_FILE_TYPE_UNKNOWN (== NULL == FALSE).
  679.  
  680.         Use the following call for a simple check :
  681.  
  682.         handle   = SPL_AllocHandle(N);
  683.         SPerr    = SPL_GetFileType(handle, filename, &filetype);
  684.                    SPL_FreeHandle(handle);
  685.  
  686.         This handle should NOT be used for any further operations
  687.         on the file (will be opened and checked twice but only
  688.         closed once, etc).
  689.         Initialization operations are allowed nevertheless
  690.         (e.g. SPL_InitHandleAsClip() ).
  691.  
  692.         Note, that this function fills in FILETYPES, not SUBTYPES.
  693.         For e.g. writing you must specify SUBTYPES.
  694.  
  695.         FILETYPES are only for short identification and do only
  696.         specify the global file type (8SVX, ST).
  697.  
  698.    INPUT(S)
  699.  
  700.         handle   - a valid handle
  701.         filename - a valid AmigaDOS FilePath and -Name
  702.         filetype - pointer to ULONG for SP_FILETYPE-Value
  703.  
  704.    RESULT
  705.  
  706.         NULL or an adequate SPERR-Errorcode.
  707.  
  708.    SEE ALSO
  709.  
  710.         SPL_AllocHandle(), SPL_FreeHandle()
  711.  
  712.